home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / maximus / mul100.zip / MUL.DOC < prev    next >
Text File  |  1993-02-09  |  18KB  |  368 lines
  1.   ┌─┐                                                                      ┌─┐
  2.   └─┼──────────────────────────────────────────────────────────────────────┼─┘
  3.     │                                                                      │
  4.     │                           MUL Version 1.00                           │
  5.     │                                                                      │
  6.     │              Maximus-CBCS User Base Script Interpreter               │
  7.     │                                                                      │
  8.     │                                                                      │
  9.     │                  DISTRIBUTED AS LOW COST SHAREWARE                   │
  10.     │                                                                      │
  11.     │                                                                      │
  12.     │       (C) Copyright 1990-1993 by CodeLand, All Rights Reserved       │
  13.     │                                                                      │
  14.     │                      Created Febuary 9th, 1993.                      │
  15.     │                                                                      │
  16.     │             Written by Colin Wheat of Fidonet 3:690/613              │
  17.     │                                                                      │
  18.   ┌─┼──────────────────────────────────────────────────────────────────────┼─┐
  19.   └─┘                                                                      └─┘
  20.  
  21.  
  22.  
  23.   ┌──────────────────────────────────────────────────────────────────────────┐
  24.   └─ LICENCE ────────────────────────────────────────────────────────────────┘
  25.  
  26.     1. DISTRIBUTION.  YOU MAY COPY AND DISTRIBUTE  VERBATIM COPIES  OF
  27.        THE MUL EXECUTABLE CODE  AS  YOU  RECEIVE  IT, IN  ANY  MEDIUM,
  28.        PROVIDED  THAT YOU  CONSPICUOUSLY AND APPROPRIATELY  PUBLISH ON
  29.        EACH COPY A VALID COPYRIGHT NOTICE;  KEEP INTACT THE NOTICES ON
  30.        ALL FILES  THAT  REFER TO THIS  LICENSE AGREEMENT  AND  TO  THE
  31.        ABSENCE  OF  ANY  WARRANTY;  PROVIDE  UNMODIFIED  COPIES OF THE
  32.        DOCUMENTATION AS PROVIDED WITH THE PROGRAM;  AND GIVE ANY OTHER
  33.        RECIPIENTS OF MUL  A COPY OF THIS LICENSE AGREEMENT  ALONG WITH
  34.        THE PROGRAM. YOU MAY CHARGE A DISTRIBUTION FEE FOR THE PHYSICAL
  35.        ACT OF TRANSFERING  A COPY,  BUT  NO MORE THAN IS  NECESSARY TO
  36.        RECOVER  YOUR ACTUAL COSTS  INCURRED IN THE TRANSFER.
  37.  
  38.     2. COPYING.  YOU MAY NOT COPY,  SUBLICENSE, DISTRIBUTE OR TRANSFER
  39.        MUL    EXCEPT  AS   EXPRESSLY  PROVIDED   UNDER  THIS   LICENSE
  40.        AGREEMENT.    ANY   ATTEMPT   OTHERWISE  TO  COPY,  SUBLICENSE,
  41.        DISTRIBUTE OR TRANSFER MUL IS VOID  AND YOUR RIGHTS  TO USE THE
  42.        PROGRAM UNDER THIS LICENSE AGREEMENT SHALL BE TERMINATED.
  43.  
  44.     3. MODIFICATION.  WITH  THE  EXCEPTION  OF ARCHIVING  METHOD,  MUL
  45.        SHOULD NOT BE  DISTRIBUTED  IN ANY MODIFIED FORM.  THE COMPLETE
  46.        ARCHIVE SHOULD BE DISTRIBUTED CONTAINING THE ORIGINAL FILES. IT
  47.        MAY BE RE-PACKAGED USING A DIFFERENT ARCHIVAL METHOD AS LONG AS
  48.        THE  CONTENTS  OF  THE  ARCHIVE  ARE THE SAME  AS THAT  OF  THE
  49.        DISTRIBUTION KIT. ADDITIONAL FILES MAY NOT BE ADDED TO ARCHIVE.
  50.  
  51.     4. PROGRAM STATUS.  THIS PROGRAM  IS DISTRIBUTED AS LOW COST SHARE
  52.        WARE, NOT PUBLIC DOMAIN NOR FREEWARE.  PAYMENT OF THE  REQUIRED
  53.        FEE IS MANDATORY FOR CONTINUED USE OF THE PROGRAM. ALL USERS OF
  54.        THE PROGRAM SHOULD REGISTER THE PRODUCT  USING THE REGISTRATION
  55.        FORM SUPPLIED WITH THE PACKAGE.
  56.  
  57.     5. DISCLAIMER.  USE THIS PROGRAM AT YOUR OWN RISK.  NO WARRANTY IS
  58.        STATED OR IMPLIED. THE AUTHOR  SHALL  NOT BE  HELD  RESPONSIBLE
  59.        FOR ANY DAMAGES RESULTING FROM IT'S USE DIRECTLY OR INDIRECTLY.
  60.  
  61.  
  62.  
  63.   ┌──────────────────────────────────────────────────────────────────────────┐
  64.   └─ INTRODUCTION ───────────────────────────────────────────────────────────┘
  65.  
  66.         MUL (Maximus User Language) is a program that runs scripts
  67.         written in a subset of the C language, with special features
  68.         suited to the Maximus-CBCS User Base.
  69.  
  70.         Special functions and variables are included which will modify
  71.         the User Base as well as generate reports for display on your
  72.         Bulletin Board and run regular maintenance. MUL is very flexible
  73.         and almost the only limitation upon what can be done is the
  74.         script writing ability of the user.
  75.  
  76.         Scripts can be as simple as the "Hello, world" echo to the
  77.         screen, or as interesting as the one run to give the result
  78.         shown below (CALLSTAT.SCR) ..
  79.  
  80. ┌────────────────────────────────────────────────────────────────────────────┐
  81. │  Caller Statistics Report       MUL v1.00  -  the Maximus User Language    │
  82. │┌──────────────────────────────────────────────────────────────────────────┐│
  83. ││                                                     ┌──────────────────┐ ││
  84. ││                  System Calls Graph                 │   System Calls   │ ││
  85. ││ ┌─   ┌───────────────────────────────────────────┐  ├──────────────────┤ ││
  86. ││ │100 ┤ █   █                                     │  │   1          172 │ ││
  87. ││ │    ┤ █   █                                     │  │   2 -   9    185 │ ││
  88. ││ │ 80 ┤ █   █                                     │  │  10 -  19     31 │ ││
  89. ││ U    ┤ █   █                                     │  │  20 -  29     21 │ ││
  90. ││ s 60 ┤ █   █                                     │  │  30 -  39     16 │ ││
  91. ││ e    ┤ █   █                           █       █ │  │  40 -  49      8 │ ││
  92. ││ r 40 ┤ █   █                           █       █ │  │  50 -  74     16 │ ││
  93. ││ s    ┤ █   █   █                       █       █ │  │  75 -  99     16 │ ││
  94. ││ │ 20 ┤ █   █   █   █   ▄       ▄   ▄   █   █   █ │  │ 100 - 249     51 │ ││
  95. ││ │    ┤ █   █   █   █   █   ▄   █   █   █   █   █ │  │ 250 - 399     23 │ ││
  96. ││ │  1 ┤ █   █   █   █   █   █   █   █   █   █   █ │  │ 400+          55 │ ││
  97. ││ │    └─┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬─┘  │  Calls    Users  │ ││
  98. ││ │      1  2-9  10  20  30  40  50  75 100 250 400+  └──────────────────┘ ││
  99. ││ └────────────────── Calls Logged ────────────────┘                       ││
  100. │└ Out of a total of  595 accounts,  251 were accessed in the last  30 days ┘│
  101. └────────────────────────────────────────────────────────────────────────────┘
  102.  
  103.         The possibilites for MUL are endless and all that is necessary
  104.         is a basic understanding of the C language. (Actually, not even
  105.         that is necessary as many SysOps are likely to write a program
  106.         for their own use and then release it to the Network.)
  107.  
  108.         This package is SHAREWARE software. The SHAREWARE classification
  109.         allows full public distribution, try before you buy, and free
  110.         evaluation of the package. Please register using the provided
  111.         registration form (REGISTER.DOC) after a reasonable evaluation
  112.         period. Our thanks for your support. We hope you find MUL as
  113.         useful on your system as we have on ours since it's development
  114.         during 1992.
  115.  
  116.  
  117.  
  118.   ┌──────────────────────────────────────────────────────────────────────────┐
  119.   └─ ARCHIVE CONTENTS ───────────────────────────────────────────────────────┘
  120.  
  121.         MUL.EXE         -   The MUL interpreter executable (DOS version)
  122.         MUL.INI         -   Sample configuration file
  123.         MUL.DOC         -   Main package documentation
  124.         MULQKREF.DOC    -   MUL quick reference (three pages)
  125.         MULFNREF.DOC    -   Intrinsic function reference documentation
  126.         MULVAREF.DOC    -   Intrinsic variable reference documentation
  127.         REGISTER.DOC    -   Package registration form
  128.  
  129.   ┌────────────────────────────────────┐
  130.   └─ SAMPLE SCRIPTS ───────────────────┘
  131.  
  132.         BSORT.SCR       -   Maximus user base sorting
  133.         BSORT.BAT       -   Batch file to run Bsort
  134.         CALLERS.SCR     -   Today's callers online avatar report
  135.                             generator
  136.         CALLSTAT.SCR    -   Maximus user base call statistics
  137.                             avatar report
  138.         EXPRPT.SCR      -   Sysop text file report of account
  139.                             expiry information
  140.         EXPWARN.SCR     -   Post expiry warning messages to users
  141.                             using Msgpost
  142.         MAKUSER.SCR     -   Batch file account addition via text
  143.                             file description
  144.         MAKUSER.DAT     -   Sample data file for MakUser
  145.         MAXPLAY.SCR     -   Plays Maximus TUNES.BBS tunes
  146.         MAZE.SCR        -   Demonstration - generate a maze on
  147.                             screen
  148.         MORSE.SCR       -   Plays command line in morse code
  149.         PACK.SCR        -   Maximus user base delete scan and pack,
  150.                             full screen
  151.         PACK.BAT        -   Batch file to run Pack
  152.         PHONEFIX.SCR    -   Adjust all user base phone fields to
  153.                             preset mask
  154.         REGUSER.LZH     -   New user registration system by John Daniels
  155.         RDUSR.SCR       -   Simple list users to system console
  156.         REMDEM.SCR      -   Remove demote settings for all user records
  157.         SETCRDT.SCR     -   Set credit value for all user records
  158.         TOPUSER.SCR     -   Top users online avatar report generator
  159.         VIEW.SCR        -   UEDit style read only edit screen, full
  160.                             screen
  161.         VIEW.BAT        -   Batch file to run View
  162.  
  163.  
  164.  
  165.   ┌──────────────────────────────────────────────────────────────────────────┐
  166.   └─ RUNNING MUL ────────────────────────────────────────────────────────────┘
  167.  
  168.         To run MUL enter at the operating system level:
  169.  
  170.          MUL [/p<script file path & name>] [script arguments]
  171.  
  172.         If filename is not specified, MUL will attempt to run MUL.SCR in
  173.         the current directory. The default extension is .SCR.
  174.  
  175.         Example: MUL -pVIEW
  176.  
  177.  
  178.  
  179.   ┌──────────────────────────────────────────────────────────────────────────┐
  180.   └─ COMMAND LINE SWITCHES ──────────────────────────────────────────────────┘
  181.  
  182.         Syntax:  MUL [-switch -switch ...] [script arguments ...]
  183.  
  184.          -p        Program script file path & name
  185.          -v        Verbose mode screen messages
  186.          -b        BIOS screen writing
  187.          -r        CGA snow reduction
  188.          -m        Force monochrome text attributes
  189.          -i        Configuration file path & name
  190.          -?        Program help screen
  191.  
  192.  
  193.  
  194.   ┌──────────────────────────────────────────────────────────────────────────┐
  195.   └─ DO I HAVE TO KNOW 'C' TO USE MUL? ──────────────────────────────────────┘
  196.  
  197.         If you have no knowledge of C, this is an ideal way to start on
  198.         your way to a better understanding.  No "include" files or
  199.         "define"s are necessary and functions do not need to be declared
  200.         as a type.  Of course, the more you know about C the bigger and
  201.         better your scripts will be, but this will come with time and an
  202.         effort to learn.  A list of already declared functions and
  203.         variables are included in the documentation.
  204.  
  205.  
  206.  
  207.   ┌──────────────────────────────────────────────────────────────────────────┐
  208.   └─ TO WRITE YOUR FIRST SCRIPT ─────────────────────────────────────────────┘
  209.  
  210.         A basic script consists of the main part of the program, curly
  211.         brackets to signify the start and finish of the code and the
  212.         lines of code which tell MUL what to do.  Here is a sample of a
  213.         simple script.  Type it in yourself and see how it works.
  214.  
  215.                 main()
  216.                 {
  217.                     printf ("My first script.\n");
  218.                 }
  219.  
  220.         Type the above example into a file called (for this example)
  221.         FIRST.SCR and then execute the script by entering the following
  222.         line at the system prompt. Note that MUL will assume a script
  223.         name extension of ".SCR" if none is given on the command line.
  224.  
  225.         mul -pFIRST
  226.  
  227.         The following line should be printed to the screen.
  228.  
  229.         My first script.
  230.  
  231.         Congratulations, you've just executed your first MUL script! (-8
  232.  
  233.         More complex and useful scripts are easily developed, the scope
  234.         and purposes for which are only limited by your imagination.
  235.         We're not able to enter into a full programing tutorial here,
  236.         but all the intrinsic (built in) MUL functions available are
  237.         fully detailed in the MULFNREF.DOC file, which also includes
  238.         full working script examples for every function. All the
  239.         intrinsic variables are detailed in the MULVAREF.DOC file.
  240.  
  241.         Rather than attempt a full programming tutorial for the C
  242.         language, a subset of which MUL scripts are based upon, we'll
  243.         quickly step through one of the example scripts, called
  244.         EXPWARN.SCR.  Firstly however, you may wish to execute a few of
  245.         the example scripts provided. Try the following commands from
  246.         the system prompt.
  247.  
  248.         mul -pMORSE sos
  249.  
  250.         mul -pMAZE
  251.  
  252.         mul -pVIEW
  253.  
  254.  
  255.  
  256.   ┌──────────────────────────────────────────────────────────────────────────┐
  257.   └─ THE PARTS THAT MAKE UP A SCRIPT ────────────────────────────────────────┘
  258.  
  259.         Comments can be placed in a script by placing two forward
  260.         slashes at the beginning of the line.
  261.  
  262.         i.e.
  263.          // MUL is (C) Copyright 1990-93 by CodeLand Australia
  264.  
  265.         This example script will scan your user file for records with a
  266.         date expiry setting.  Each record found is checked for a match
  267.         of days to expiry with the 'warndays' variable setting. Where
  268.         matches are found, the 'warnexp' command line entry is executed.
  269.         This enables functions such as posting a message to warn users
  270.         of a pending expiry.
  271.  
  272.         This script is based on the executable of the same name, also by
  273.         Colin Wheat, originally written for Simon Blears of 3:690/601.
  274.  
  275.         Declaration of files is as follows.  Paths may be used.
  276.  
  277.          char *ufile = "USER.BBS";   // Path & name of Maximus user file
  278.          //char *ufile = "C:\\BBS\\USER.BBS";
  279.  
  280.         Declaration of variables:
  281.  
  282.          int warndays=14;            // Issue warning days before expiry
  283.          char *warnexp = "MsgPost -TC:\\Util\\WarnExp.Txt \"-F%s\"";
  284.  
  285.         The *warnexp variable posts a message to accounts with expiry
  286.         pending in 'warndays' days.  MsgPost will post a message to the
  287.         user warning of the pending expiry.
  288.  
  289.          char *banner = "EXPWARN v1.00";             // Script banner
  290.          char *desc = "Warn of Pending Expiry";      // Description
  291.  
  292.          main ()                                     // Main program
  293.          {
  294.              printf ("\n%s - %s\n\n",banner,desc);   // Announce
  295.              if (!BaseOpenR (ufile))
  296.              {
  297.                  printf ("ERROR opening user file %s\n",ufile);
  298.                  saybibi ();
  299.                  exit ();
  300.              }
  301.  
  302.         This first part will print the program name and version to the
  303.         screen (see contents of variable *banner, above) and what the
  304.         program will do.  If the file that the program is trying to open
  305.         isn't there or can't be opened for use by the program an error
  306.         message will be written to the screen.  In this case, the
  307.         function saybibi is called (the function is at the end of this
  308.         program) and the program will exit.
  309.  
  310.              scanufile ();                   //Process the user file
  311.  
  312.              BaseClose ();                   // Close the user base
  313.              saybibi ();                     // Was it good for you too?
  314.          }
  315.  
  316.         The last part of the main program calls three functions one of
  317.         which will exit the program, one (BaseClose) of which is an
  318.         already declared function (see other documentation with this
  319.         package, and one of which is explained below.
  320.  
  321.          scanufile ()                        // Process the user file
  322.          {
  323.              int rec=1;
  324.              char buf[128];
  325.  
  326.         More variables are declared.
  327.  
  328.              while (BaseRead (rec++))         // Read all records
  329.              {
  330.                  if (And (USRxpflag,XP_DATE)) // If expire by date
  331.                  {
  332.                      if (BaseDaysXpry () == warndays)
  333.                      {
  334.                          printf("Warning: %04u %-25s\n",rec,USRname);
  335.                          sprintf (buf,warnexp,USRname);
  336.                          system (buf);
  337.                      }  //end of if BaseDays
  338.                  } //end of if USR
  339.              }  //end of while loop
  340.          }  //end of function scanufile
  341.  
  342.         While there are records to be read in the userfile this loop
  343.         will read the record, check the expiry date, and if the expiry
  344.         date is 14 days or less a way from todays date will print the
  345.         warning message and username.
  346.  
  347.          // Byebye
  348.          saybibi ()
  349.          {
  350.              puts ("\nExpWarn done!\n");
  351.          }
  352.  
  353.          // End of script
  354.  
  355.  
  356.  
  357.   ┌─ Happy script writing! ──────────────────────────────────────────────────┐
  358.   └──────────────────────────────────────────────────────────────────────────┘
  359.    Documentation by Crossroads Computer Documentation and CodeLand Australia
  360.  
  361.                        CROSSROADS COMPUTER DOCUMENTATION
  362.                     Fidonet 3:690/310  Worldnet 61:7200/310
  363.                    P.O. Box 3 Northlands W.A. 6021 AUSTRALIA
  364.  
  365.                                CODELAND AUSTRALIA
  366.                   P.O.Box 351, Kalamunda W.A. 6076, AUSTRALIA
  367.  
  368.